home *** CD-ROM | disk | FTP | other *** search
/ BCI NET 2 / BCI NET 2.iso / archives / utilities / shell / pipe-1.5.lha / pipe / Pipe.doc next >
Encoding:
Text File  |  1995-01-12  |  6.6 KB  |  176 lines
  1.  
  2. INTRODUCTION
  3.  
  4.     Pipe implements anonymous pipes in AmigaShell, taking advantage of an
  5.     undocumented feature built in it since OS version 2.04.
  6.  
  7.     Anonymous piping, familiar to many from UNIX systems, means directing
  8.     the output of one program to the input of another, without using
  9.     temporary files. Many third part Amiga shells emulate pipes using
  10.     temporary files, but this is slow and can take up a lot of RAM or disk
  11.     space. Pipe uses the PIPE: device to create true pipes between
  12.     programs.
  13.  
  14. LEGAL
  15.  
  16.     Pipe is Copyright © 1995 by Osma Ahvenlampi, All Rights Reserved.
  17.     Permission granted to distribute free of charge, in unchanged form,
  18.     provided this documentation file is accompanied with the program.
  19.     Permission granted to include on freely distributable software
  20.     libraries such as Fred Fish's software library and the Aminet CD-ROM.
  21.  
  22.     Pipe is provided as is, without any kind of warranty. By using Pipe,
  23.     the user accepts full responsibility for possible damage or data loss
  24.     that might occur, directly or indirectly, from using Pipe.
  25.  
  26.     Pipe is GIFTWARE. If you use Pipe, send me a gift (your own program,
  27.     beer, chocolate, your sister, a new computer, a money donation, etc),
  28.     the address is in the end of this document.
  29.  
  30. FEATURES
  31.  
  32.     - 100% pure, can be made resident
  33.     - Can be used even with programs that can not use stdin and/or stdout, 
  34.       by using the IN: and OUT: pseudo-files.
  35.     - Flushes pipes on error conditions
  36.     - Works 100% with AmigaDOS scripts
  37.     - Will not trash out on invalid command lines such as "Echo | | More |".
  38.  
  39. INSTALLATION
  40.  
  41.     Pipe needs the PIPE: device mounted. For OS 2.1 and later, this is
  42.     done by moving the PIPE icon from SYS:Storage/DOSDrivers to
  43.     SYS:Devs/DOSDrivers, and rebooting the machine.
  44.  
  45.     Pipe has to be in the Shell search path. A recommended place is C:. If
  46.     you use Pipe a lot, I suggest you make it resident, by adding the
  47.     command "Resident ADD C:Pipe PURE" in S:User-Startup. This will take
  48.     less than 2 kilobytes of memory, and will make use of pipes
  49.     significantly faster.
  50.  
  51.     To make AmigaShell use Pipe, you need to set two shell variables,
  52.     _pchar and _mchar. _pchar is the normal pipe character (usually "|"),
  53.     while _mchar is the "multiple command" character (I recommend "||").
  54.     You can set these permanently by add to S:Shell-Startup the commands
  55.     Set _pchar "|" and Set _mchar "||"
  56.     in S:Shell-Startup (which is executed upon starting a Shell).
  57.  
  58.     If you are not sure how to activate all these without a reboot, I
  59.     suggest you add these commands to the scripts, and reboot you Amiga.
  60.     When you now start a Shell, Pipe is ready to use.
  61.  
  62. USAGE
  63.  
  64.     In the following examples, I use _pchar "|" and _mchar "||". If you
  65.     set yours to other values, adjust accordingly.
  66.  
  67.     By putting two commands on the same command line, separated from each
  68.     other with the | character, the output of the first command is
  69.     directed to the input of the second command. For example:
  70.  
  71.     List LIBS: | More
  72.  
  73.     will output the LIBS: directory listing through the More pager.
  74.  
  75.     If a command insists on having a filename argument, and will not be
  76.     satisfied with using the standard input or output, you can use the IN
  77.     and OUT: pseudo-files as filenames. Pipe will replace them
  78.     accordingly. For example:
  79.  
  80.     List LIBS: LFORMAT="Version %s%s" | Execute IN:
  81.  
  82.     will show the version information of all the libraries.
  83.  
  84.     You can also concatenate the output of two programs together by using
  85.     the "multiple command" separator. For example:
  86.  
  87.     List SYS: || Type Pipe.doc
  88.  
  89.     will output first the SYS: directory listing, then this Pipe doc file.
  90.     You can also direct these to another pipe:
  91.  
  92.     List SYS: || Type Pipe.doc | More
  93.  
  94.     For those of you who are familiar with the standard UNIX shell syntax,
  95.     the above is similar to
  96.  
  97.     ( ls -l / ; cat Pipe.doc ) | more
  98.  
  99.     used in /bin/sh.
  100.  
  101.     You can combine these in more complex ways:
  102.  
  103.     List LIBS: NOHEAD | Search IN: xpr || Type Pipe.doc | More
  104.  
  105.     will concatenate a listing of all XPR libraries and the Pipe
  106.     documentation, and show them through More.
  107.  
  108.     ( ( ls -l /usr/lib | fgrep -i xpr ) ; cat Pipe.doc ) | more
  109.  
  110.     in /bin/sh syntax.
  111.     
  112.     To get a gziped tar archive expanded in one step, use
  113.     
  114.     gzip -dc foo.tar.gz | tar -xf -
  115.  
  116.     Do not be discouraged by the seemingly complex command lines
  117.     demonstrated above. After some time, you will get used to the syntax,
  118.     and will find Pipe an essential help in Shell work.
  119.  
  120. BUGS
  121.  
  122.     OUT: will NOT work with a command that is a part of a || structure.
  123.     This is a tradeoff for having || work with a lot of input, and on the
  124.     other hand, not breaking EXECUTE. Programs should not need OUT:
  125.     anyway. Only thing I can think of that needs it is C:Sort, and there
  126.     are significantly better replacements for that.
  127.     
  128.     This is not really a bug in Pipe, but DO NOT use "More IN:" with the
  129.     C= More (version 40.2 atleast). It won't be able to handle that right,
  130.     going into a busy loop.. You can still break it from Xoper etc.
  131.  
  132.     Error situations can act weirdly. Pipe does not attempt to find out
  133.     beforehand whether the commands exist, nor does it try to break
  134.     running commands when an unknown command or other error distrupts the
  135.     pipeline. It will still flush all pipes, but this might mean that the
  136.     first commands in the pipeline might do unnecessary processing with the
  137.     output just flushed away.
  138.     
  139.     Since alias expansion is done after IN:/OUT: replacement, you can't use
  140.     aliases such as "alias psort sort in: out:". Fixing this would require
  141.     a major rewrite, and I can't see it justified by a couple of broken
  142.     programs.
  143.     
  144.     As long as we're talking about aliases, be careful with them. If
  145.     _pchar is set, "alias foo command | another" does NOT make an alias
  146.     "foo" that expands to "command | another". It makes an alias "foo"
  147.     that expands to "command", and pipes the output of the Alias command
  148.     (ie. nothing) to "another". If you want to include pipes in aliases,
  149.     quote the whole alias, as in 
  150.     alias foo "command | another"
  151.  
  152.     Please send me bug reports and suggestions on improvement. Don't
  153.     forget the gift, either ;)
  154.  
  155. HISTORY
  156.  
  157.     Version 1.5 fixes bugs in input/output redirection.
  158.     ilbmtoppm <pic.iff | pnmscale -xysize 320 200 | ppmtogif >pic.gif
  159.     works now.
  160.  
  161. AUTHOR
  162.  
  163.     Pipe is written by Osma Ahvenlampi. I am a computer engineering
  164.     student at the Helsinki University of Technology. You can reach me by
  165.     email at the address
  166.  
  167.     Osma.Ahvenlampi@hut.fi
  168.  
  169.     or by snailmail (for the time being, anyway) at the address
  170.  
  171.     Osma Ahvenlampi
  172.     Rekipellontie 2 F 55
  173.     00940 Helsinki
  174.     Finland
  175.  
  176.